.. _reporting_queries:

Reporting
============

Starting with LinOTP 2.9 a new reporting API was introduced. It can be used to
query information about the number of tokens. This can be useful for
accounting in multitenancy environments or statistical purpose.

The comprehensive API documentation can be found here:

https://www.linotp.org/doc/api/linotp.controllers.reporting.html

The basic API call is:

``https://<LINOTP>/reporting/<ReportingController>?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]``

The available controllers are:

``show``
 displays historical count data

``maximum``
 displays highest values counted

``delete_all``
 clean the counter database

``delete_before``
 delete all values in the counter database recorded before a defined date

.. tip::
 Detailed information about the handling of the session cookie can be found at
 :ref:`system_controller`


Prerequisites
--------------

The reporting API can be accessed by the token managers. The available queries
have to be configured before via policies as described in :ref:`policy-reporting`.

.. tip::
 After adding new states to be recorded in the policies the next count will be
 performed after an event was triggered potentially changing the counted value.
 So for example if a new token is enrolled the counters are recalculated and can
 be queried.

Perform Queries
-----------------

show
`````

Displays the token counters recorded over time. The output can be filtered
regarding the token states and the realms.

.. code::

 https://<LINOTP>/reporting/show?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]

**Available parameters:**

``realms`` [optional]
 Limit the counter output to the given realms.

``status`` [optional]
 Limit the counter output to tokens with of certain states.

**Explanation of the available token states:**

``active``
 counts only active tokens

``inactive``
 counts only deactivated tokens

``assigned``
 counts only tokens assigned to users

``unassigned``
 counts only tokens which are not assigned to any user

``active&assigned``
 counts tokens which are activ and assigned to an user

``active&unassigned``
 counts active tokens which are not assigned to any user

``inactive&assigned``
 counts disabled tokens assigned to users

``inactive&unassigned``
 counts disabled tokens which are not assigned to any user

.. tip::
 Please make sure to use exactly the same token states for the queries as
 defined in the reporting policies (:ref:`policy-reporting`)

* **Displays all available historical numbers of all tokens of all states**

.. code::

 https://<LINOTP>/reporting/show?session=SESSIONCOOKIE

*Example*

.. code::

 https://linotp.example.net/reporting/show?session=45e939b02[...]

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "resultset": {
            "page": 1,
            "pages": 1,
            "pagesize": 30,
            "report_rows": 30
         },
         "data": [
            {
               "count": 132,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-25 13:27:47",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "active",
               "event": "token_tokenrealm"
            },
            {
               "count": 150,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-25 13:27:47",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "total",
               "event": "token_tokenrealm"
            },
 [...]

* **Display token counts for certain realms**

.. code::

 https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&realms=REALMA,REALMB

*Example*

Show token count numbers for 'realm1' and 'realm2':

.. code::

 https://linotp.example.net/reporting/show?session=45e939b02[...]&realms=realm1,realm2


 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "resultset": {
            "page": 1,
            "pages": 1,
            "pagesize": 30,
            "report_rows": 30
         },
         "data": [
            {
               "count": 132,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-25 13:27:47",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "active",
               "event": "token_tokenrealm"
            },
            {
               "count": 150,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-25 13:27:47",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "total",
               "event": "token_tokenrealm"
            },
 [...]

            {
               "count": 300,
               "realm": "realm2",
               "description": "",
               "timestamp": "2016-07-25 13:27:54",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "active",
               "event": "token_tokenrealm"
	   },
 [...]
 }

* **Display token count numbers for certain states**

.. code::

 https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]

*Example*

Show count numbers for unassigned active tokens:

.. code::

 https://linotp.example.net/reporting/show?session=45e939b02[...]&status=unassigned%26active

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "resultset": {
            "page": 1,
            "pages": 1,
            "pagesize": 6,
            "report_rows": 6
         },
         "data": [
            {
               "count": 11,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-26 11:37:58",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "unassigned&active",
               "event": "token_enable"
            },
            {
               "count": 12,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-26 13:00:10",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "unassigned&active",
               "event": "token_init"
            },
 [..]
 }

* **Display count numbers for tokens of a certain states from particular realms**

.. code::

 https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]

*Example*

Show count numbers for unassigned+active and unassigned+inactive tokens from 'realm1':

.. code::

 https://linotp.example.net/reporting/show?session=45e939b02[...]&status=unassigned%26active,unassigned%26inactive&realms=realm1

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "resultset": {
            "page": 1,
            "pages": 1,
            "pagesize": 12,
            "report_rows": 12
         },
         "data": [
            {
               "count": 0,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-26 11:37:58",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "unassigned&inactive",
               "event": "token_enable"
            },
            {
               "count": 8,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-26 11:37:58",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "unassigned&active",
               "event": "token_enable"
            },
            {
               "count": 0,
               "realm": "realm1",
               "description": "",
               "timestamp": "2016-07-26 13:00:10",
               "detail": "",
               "value": "",
               "session": "",
               "parameter": "unassigned&inactive",
               "event": "token_init"
            },
 [..]
 }


maximum
````````

Display the highest number counter for token of a certain state in realms.

.. code::

 https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE[&realms=REALMA,REALMB,...][&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]

**Available parameters:**

``status`` [optional]

``realms`` [optional]

* **Show total number of tokens**

.. code::

 https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE


*Example*

Show highest numbers of total tokens counted for all realms:

.. code::

 https://linotp.example.net/reporting/maximum?session=45e939b02[...]

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "realm1": {
            "total": 270
         },
         "realm2": {
            "total": 178
         }
      }
   },
   "id": 1
 }

* **Show number of tokens of certain states**

.. code::

 https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]]

*Example*

Show highest numbers counted of inactive tokens for all realms:

.. code::

 https://linotp.example.net/reporting/maximum?session=45e939b02[...]&status=inactive

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "realm1": {
            "inactive": 25
         },
         "realm2": {
            "inactive": 13
         }
      }
   },
   "id": 1
 }

* **Show number of tokens of certain states from specific realms**

.. code::

 https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE&realms=REALMA[,REALMB][..]status=STATEA[%26STATEB][,STATEC[%26STATED]][..]

*Example*

Show highest numbers counted of unassigned or inactive tokens for 'realm1':


.. code::

 https://linotp.example.net/reporting/maximum?session=45e939b02[...]&status=inactive,unassigned&realms=realm1

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "realm1": {
            "unassigned": 15,
            "inactive": 25
         }
      }
   },
   "id": 1
 }


delete_all
``````````

Delete all counters from database.

.. code::

 https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all[&realms=REALMA[,REALMB][..]]
 [&status=STATEA[%26STATEB][,STATEC[%26STATED]][..]]

**Available parameters:**

``status`` [optional]

``realms`` [optional]

* **Delete all count data**

.. code::

 https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all

*Example*

.. code::

 https://linotp.example.net/reporting/delete_all?session=45e939b02[...]

.. code::

 {
   "version": "LinOTP 2.9rc2",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": 586
   },
   "id": 1
 }


* **Delete token counter of selected realms**

.. code::

 https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all&realms=REALMA[,REALMB][..]

*Example*

Delete all tokens counter from realm1:

.. code::

 https://linotp.example.net/reporting/delete_all?session=45e939b02[...]&realms=realm1

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": 432
   },
   "id": 1
 }

* **Delete token counter for selected states**

.. code::

 https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all&status=STATEA[%26STATEB][,STATEC[%26STATED][..]

*Example*

Delete all tokens counter of the state inactive or disabled:

.. code::

 https://linotp.example.net/reporting/delete_all?session=45e939b02[...]&status=inactive,disable

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": 18
   },
   "id": 1
 }


delete_before
``````````````

Delete entries from the database before a given date. The removal can be
optionally selective regarding the realm and the token states.

.. code::

 https://<LINOTP>/reporting/delete_before?session=SESSIONCOOKIE&date=YYYY-MM-DD[&realms=REALMA,REALMB,...]
 [&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]

**Available parameters:**

``date``
 the date before counters are deleted in format YYYY-MM-DD

``status`` [optional]

``realms`` [optional]

*Example*

Remove all count data recorded before 2016-07-22:

.. code::

 https://linotp.example.net/reporting/delete_before?session=45e939b02[...]&date=2016-07-22

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": 157
   },
   "id": 1
 }


*Example*

Remove count data for all active token from realm1 recorded before 2016-07-26:

.. code::

 https://linotp.example.net/reporting/delete_before?session=45e939b02[...]&status=active&realms=realm1&date=2016-07-26

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": 68
   },
   "id": 1
 }